Dokumentation Harmony.dll Scripts

Inhalt

1) Allgemeiner Aufbau eines Scriptes
2) Beschreibung der mglichen Befehle
A) Anhang: Liste der SonderTasten fr KeySupport

1) Allgemeiner Aufbau eines Scriptes
_____________________________________

Ein Script ist eine Textdatei mit der Erweiterung *.script.wav
In ihr steht eine Liste von Befehlen, die nacheinander ausgefuehrt werden.
Jeder Befehl steht in einer SECTION, in welcher die benoetigten Parameter
wie in einer INI Datei uebergeben werden. Der Name der Sektion ist beliebig
waehlbar und in [] zu setzen, jedoch wird zuerst immer die Sektion des Namens
[Execute] bearbeitet. Gross- und Kleinschreibung wird konsequent ignoriert.

Jede Sektion hat zwei Parameter:

Command= Enthaelt den Befehl, der ausgefuehrt werden soll

Next= Enthaelt den Namen der Sektion, die als naechstes ausgefuehrt
      werden soll. Dabei kann dem Sekionsnamen der Name eines anderen
      Scriptes inclusive relativem Pfad vorangestellt weren und muss
      durch ; getrennt werden. Handelt es sich um die aktuelle Datei,
	  so kann der gesamte Dateiname samt ; ausgelassen werden.
	  Folgt Next= kein Wert oder fehlt Next=, so ist die Ausfhrung
	  des Scriptes Beendet. 
	  Beispiele:
	  next=Init springt zur Sektion [Init] der aktuellen Datei
	  next=..\music\playBG.script.wav;Init Springt zur Sektion [Init]
	  in der Datei playBG.script.wav im Ordner Music
	  
Desweiteren koennen/muessen befehlspezifische weitere Parameter angegen werden
in der Form Parameter=Wert, wobei Leerzeichen vor und nach dem = verboten sind.

Alle Angaben, die nicht dieser Form entsprechen, werden als Kommentare betrachtet
und ignoriet. Jedoch sollte entsprechend der allgemeinen Konvention fuer Ini-Files
ihnen ein ; zur Kennzeichnung als Kommentar vorangestellt werden. Beispiel:

[clear]
;loescht die OutPutListe
Action=MidiTickFunction
Value=clear
next=


2) Beschreibung der mglichen Befehle
______________________________________

WriteToLog

Beschreibung:
Schreibt einen Kommentar in die Harmony.log. Dies kann zu Debugen nuetzlich sein.

Parameter:
Text: Gibt den zu schreibenden Text an

Beispiel:
[Comment]
Action=WriteToLog
Text=Kommentier mer mal ein wenig
next=


ExecProgram                !!! WARNUNG: NUR FR PROFIS GEEIGNET  !!!

Beschreibung:
Fhrt ein externes Programm oder Dokument aus.
Vornehmlich bei diesem Befehl kann es zu erheblichen systemabhaengigen Abweichungen kommen.

Parameter:
Command: Pfad und Dateiname der auszufhrenden Datei
Type  semioptional; Wird als Wert document eingetragen, so wird signalisiert, dass es sich
      nicht um ein Programm handelt, sondern um ein Dokument, das mit seiner 
	  verknuepften Anwendung geoeffnet werden soll
Wait  semioptional; Wird der Wert True uebergeben, so wird nach moeglichkeit das Script und
      somit auch der Maker so lange angehalten, bis das gestartete Programm / Anwendeung
	  beendet ist.

Parameter bei Dokumenten -> NUR fuer Type=document
Display   wird der Wert showerrors uebergeben, so werden eventuelle Fehlermeldungen angezeigt
          implementierung ist systemabhaengig
		  
Parameter bei Programmen -> ignored fuer Type=document
Display   gibt den Displaystatus des Programmes beim Starten an. Moegliche Werte:
          minimized        Startet das Programm minimiert.
	   	  maximized        Startet das Programm maximiert.
		  normal           Startet das Programm im Normalmodus.
		  minimizedactive  Startet das Programm minimiert und im Hintergrund.
		  notactivated     Startet das Programm im Hintergrund.
		  alles andere     Startet das Programm mit default Einstellungen
Priority  Stellt die Rechenleistungsprioitaet des Programmes an. Moegliche Werte:
          idle             minimale Prioritaet fuer Hintergrundprozesse oder Services
		  hight			   erhoehte Prioritaet als default Einstellung
		  realtime		   maximale Rechenleistung VORSICHT: Kann zum Stillstand fuehren
		  alles andere     default Einstellungen
Result    optional; gibt den Dateinamen einer Rueckgabewertdatei an.
          enthaellt die Datei in der ersten Zeile eine Zeichenkette, die eine Ganzzahl
		  repraesentiert, so wird diese in die OutPutListe eingereit, sonst -1
		  
Beispiel:

[execute]
;Aufrufen der Homepage
Action=ExecProgram
Type=document
command=http://www.inelukis-rpgmaker.de.vu
next=

MciCommand                  !!!  WARNUNG: NUR FR PROFIS GEEIGNET  !!!

Beschreibung:
Gibt einen MCI-Befehl an das Windowssubsystem weiter.
Eine Beschreibung saemtlicher MCI-Befehle ist zur Zeit im Internet unter
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/multimed/mci_6hdf.asp
zu finden. Die Uebergabe erfolgt als String und nicht als Message.
Rueckgabewerte und Fehlermeldungen werden in die Harmony.log geschrieben.

Parameter:
Command   enthaelt den kompletten MCI-String
          der String %path% wird hierbei durch den Pfad zur aktuell ausgefuehrten Datei ersetzt

Beispiel:

[execute]
Action=WriteToLog
text=Abspielen von ..\mp3\demo.mp3
next=open mp3

[open mp3]
acTion=mcicommand
command=open "%path%\..\mp3\demo.mp3" alias mp3
next=play mp3

[play mp3]
Action=mcicommand
command=play mp3 wait
next=close mp3


[close mp3]
action=mcicommand
command=close mp3
next=exit

[exit]
action=WriteToLog
text=..\mp3\demo.mp3 abgespielt
next=

MidiTickFunction

Beschreibung:
Setzt das Verhalten der GetMidiTick-Funktion des Makers

Parameter:
value   Setzt den Interpretationsmodus. Moegliche Werte:
        original    Stellt den Standardmodus (Playpos der BGM) wieder her.
		output      GetMidiPos liest jeweils einen Wert aus der OutPutListe.
		clear       Loescht die gesamte OutPutListe. Aendert nicht den Modus.
		
Beispiel:
[output]
;OutPutListe wird bei GetMidiPos ausgelesen
Action=MidiTickFunction
Value=output
next=

AddOutPut

Beschreibung:
Haengt einen Wert an die OutPutListe an.

Parameter:
Value   Wert, der geschrieben werden soll. Dabei handelt es sich um eine
        Ganzzahl im Bereich von -2147483648 bis 2147483647
		
Beispiel:

[Schreibe 13]
;Schreibt 13 in die OutPutLists
Action=AddOutPut
Value=13
next=

EnableKeySupport

Beschreibung:
Aktiviert bzw deaktiviert die Tastendruckueberwachung (KeySupport)

Parameter:
enable  Moegliche Werte:
        True   Aktiviert die Ueberwachung
		False  Deaktiviert die Ueberwachung
		
Beispiel:

[KeySupport An]
;Schaltet den KeySupport ein
Action=EnableKeySupport
Enable=True
next=

[KeySupport Aus]
;Schaltet den KeySupport aus
Action=EnableKeySupport
Enable=False
next=

RegisterKeyDownEvent

Beschreibung:
Registriert einen Tastendruck mit einer Ganzzahl.
Ist KeySupport aktiviert, wird bei besagtem Tastendruck die Ganzzahl an die
OutPutList angehaengt. Man beachte: Tastendrittbelegungen (AltGr) werden nicht
akzeptiert. Daher ist im Gegensatz zu $ das Zeichen @ KEINE Taste.

Parameter:
Key          Tasten bzw Sondertastenname -> Siehe Anhang
Value        Ganzzahl die bei Tastendruck an die OutPutList angehaengt wird

Beispiel:

[9]
Action=registerKeyDownEvent
Key=9
Value=9 
next=tab
 
[tab]
Action=registerKeyDownEvent
Key=(Tab)
Value=10 
next=

RegisterKeyUpEvent

Beschreibung:
Registriert einen Tastenrelease mit einer Ganzzahl.
Ist KeySupport aktiviert, wird bei besagtem Loslassen der Taste die Ganzzahl an die
OutPutList angehaengt. Man beachte: Tastendrittbelegungen (AltGr) werden nicht
akzeptiert. Daher ist im Gegensatz zu $ das Zeichen @ KEINE Taste.

Parameter:
Key          Tasten bzw Sondertastenname -> Siehe Anhang
Value        Ganzzahl die bei Loslassen der Taste an die OutPutList angehaengt wird

Beispiel:

[9]
Action=registerKeyUpEvent
Key=9
Value=-9
next=tab
 
[tab]
Action=registerKeyUpEvent
Key=(Tab)
Value=-10 
next=

RegisterCheatEvent

Beschreibung:
Registriert einen Cheats mit einer Ganzzahl.
Ist KeySupport aktiviert, wird bei Eingabe des Cheats die Ganzzahl an die
OutPutList angehaengt. Auch Tastendrittbelegungen werden akzeptiert, da diese
als selbststaendige Zeichen fungieren. Funktionstasten werden jedoch bei der
Cheatcodeeingabe IGNORIERT, ausser (Enter). Dass heisst: Inel[F2]uki = Ineluki

Parameter:
Key         Cheatcode; Gross und Kleinschreibung wird NICHT unterschieden -> siehe 1)
Value       Ganzzahl die bei Eingabe an die OutPutList angehaengt wird

Beispiel:

[cheat]
Action=registerCheatEvent
Cheat=Ineluki
Value=13
next=

EnableMouseSupport

Beschreibung:
Aktiviert bzw Deaktiviert die Mausunterstuetzung.

Parameter:
Enable       ist dieser Wert true wird die Mausunterstuetzung eingeschaltet, ist er
             false, wird sie wieder ausgeschaltet
ID           Ganzzahl die vor den Mausdaten an die OutPutList gesendet wird
Automatic    (optional) Ist dieser Wert true, dann werden alle 500 ms Mausdaten an die OutPutListe
             gesendet. Ist dieser Wert false, dann geschieht dies nur durch einen
             Aufruf von GetMousePosition. Der Standardwert ist false.

Beispiel:

[Execute]
; schaltet die Mausunterstuetzung an
Action=EnableMouseSupport
Enable=true
ID=-9
next=

[Execute]
; schaltet die Mausunterstuetzung aus
Action=EnableMouseSupport
Enable=false
next=

GetMousePosition

Beschreibung:
Sendet die Mausdaten. Zuerst wird die ID gesendet, danach folgen unmittelbar die
X-Position und die Y-Position in Pixel (0..320, 0..240) und die Maustastenzahl.
Die Maustastenzahl ist 0, wenn keine Maustaste gedrueckt ist, 1 fuer die linke, 
2 fuer die rechte und 3 fuer beide Maustasten.

Parameter:
keine

Beispiel:

[Execute]
; Sendet die Mausdaten
Action=GetMousePosition
next=

SetDebugLevel

Beschreibung:
Ausserst nuetzliche Funktion, wenn es darum geht, Fehler in den Scripten aufzuspuehren.
Sie bestimmt, welche Informationen in der Harmony.Log gespeichert werden sollen.

Parameter:
Level       Gibt das Debuglevel an. Erlaubt sind Werte zwischen 0 und 3.
            Voreingestellt ist ein DebugLevel von 0.
  level 0 : Nur Kommentare und Fehlermeldungen
  level 1 : level 0 + wichtige Funktionsaufrufe
  level 2 : level 1 + alle Sktiptfunktionen und einige Parameter
  level 3 : level 2 + Originalfunktionen + alle Parameter

Beispiel:

[Execute]
; Setzt die Debuginformationen auf intensiv
Action=SetDebugLevel
Level=2
next=



A) Anhang
__________

Num(*) , Num(-) , Num(5) , Num(+)

(F1) ,  (F2) ,  (F3) , (F4)  , (F5)  , (F6)
(F7) ,  (F8) ,  (F9) , (F10) , (F11) , (F12)

(Esc) , (Tab) , (Enter) , (Strg) , (Alt)

(BackSpace) , (Space)
(CapsLock) , (NumLock) , (ScrollLock)

(Einfg) , (Pos1) , (BildHoch) 
(Entf)  , (Ende) , (BildRunter) 

(Hoch) , (Runter) , (Links) , (Rechts)

(LShift runter) , (RShift runter)
(LShift hoch) , (RShift hoch)